Skip to content

fix(concerto-core): remove ESM entrypoint from sideEffects to enable package-level tree shaking - #1263

Closed
mttrbrts wants to merge 8 commits into
mainfrom
fix/tree-shaking-sideeffects
Closed

mttrbrts wants to merge 8 commits into
mainfrom
fix/tree-shaking-sideeffects

Conversation

@mttrbrts

@mttrbrts mttrbrts commented Jun 14, 2026 •

Copy link
Copy Markdown
Member

Closes #1261.

Makes the 7 published @accordproject/* packages tree-shakeable in web bundles, without breaking existing consumers: additive ESM output alongside the existing CJS/UMD, conditional exports, sideEffects narrowed to the real side effect, and the dayjs.extend() calls consolidated into one module.

Rebased on current main (was 10 behind) and re-verified end-to-end. Rishabh's original commits and DCO sign-offs are preserved.

What changed

  • sideEffects on every package — narrowed to just the module that has a real load-time side effect. In concerto-core that is dayjs-setup (the dayjs.extend() calls for UTC / quarterOfYear / duration / minMax), emitted as a standalone file so the main ESM bundle stays fully tree-shakeable at the package boundary.
  • Conditional exports — import → dist/esm/index.mjs, require → dist/index.js, types → dist/index.d.ts. The "./dist/*" escape hatch is kept so existing deep-import consumers keep resolving (non-breaking over encapsulation for this PR).
  • Additive ESM build — esbuild emits dist/esm/index.mjs per package; existing CJS (dist/index.js) and UMD (dist/concerto-*.js) outputs are unchanged.
  • dayjs-setup emitted as .mjs (not .js) — the package is not "type": "module", so a .js file containing ESM is parsed as CJS by Node and is ambiguous. sideEffects points at ./dist/esm/dayjs-setup.mjs in lockstep.
  • DEVELOPERS.md documents that the monorepo must be built in dependency order (npm run build), because each package's exports.import resolves to its dist/esm/index.mjs.

Verification (all green on the rebased branch)

Gate Check Result
Build Ordered build; all 7 packages emit CJS + ESM (+ UMD where present); concerto-core emits dist/esm/dayjs-setup.mjs ✅
Tests unchanged Full suite 1,679 passing / 0 failing; no modifications to any existing test file (1 new browser-E2E spec added) ✅
Package tree-shaking Rollup: util-only import → 22.5 KB, concerto-core entirely absent; ModelManager import → 579 KB (minified) pulling core in as expected ✅
Browser E2E Playwright 3/3 — CTO parser UMD, ModelManager UMD, DateTimeUtil dayjs plugins all functional in-browser ✅
Non-breaking compat From packed tarballs: CJS require, ESM import, deep dist/* import, and node16/nodenext type resolution all work. The only tsc errors are 5 pre-existing TS8023 JSDoc errors also present on published 4.2.0 — zero new errors ✅
dayjs side effect DateTime fromJSON/toJSON round-trip + UTC plugin active in both CJS and ESM consumption paths — the tree-shaker does not drop dayjs-setup ✅

Known limitation (tracked as follow-up)

Per-export tree-shaking inside concerto-core does not work yet — importing 1 export vs all differs by ~0.14%. Root cause: the ESM build is bundle: true, producing a CJS-in-ESM blob, forced because 58/59 concerto-core/src files use TypeScript export = / import X = require() (illegal as native ESM, TS1203).

A throwaway spike migrating one leaf module (securityexception.ts) to native ESM with bundle: false measured 595,862 B → 22,908 B for a single export (96.2% reduction), confirming the win is real. Full migration of concerto-core (+ concerto-util) is a mechanical, bottom-up ~3–5 dev-day effort, tracked as a follow-up epic — out of scope for this PR so the "tests pass unchanged" guarantee is never at risk.

Scope

  • ✅ Package-level tree-shaking, non-breaking, all existing tests pass unchanged.
  • ⬜ Full native-ESM source migration for per-export tree-shaking — deferred to the follow-up epic.
  • ⬜ Narrowing the ./dist/* escape hatch — deliberately not done (would break deep-import consumers).

@Rishabh060105

Rishabh060105 commented Jun 15, 2026 •

Copy link
Copy Markdown
Contributor

Hi @mttrbrts, I think I would prefer dayjs-setup.mjs since the package does not use type:module.This way we can also reduce ambiguity.

@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.

@github-actions github-actions Bot added the Stale label Jul 3, 2026
@Rishabh060105

Rishabh060105 commented Jul 16, 2026 •

Copy link
Copy Markdown
Contributor

@github unstale

@github-actions github-actions Bot removed the Stale label Jul 17, 2026
@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.

@github-actions github-actions Bot added the Stale label Aug 1, 2026
@Rishabh060105

Copy link
Copy Markdown
Contributor

@github unstale

@github-actions github-actions Bot removed the Stale label Aug 2, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.

@github-actions github-actions Bot added the Stale label Aug 18, 2026
@mttrbrts mttrbrts removed the Stale label Aug 28, 2026
Rishabh Jain and others added 3 commits August 28, 2026 10:01
Signed-off-by: Rishabh Jain <rishabhj2005@email.com>
…package-level tree shaking

Listing `./dist/esm/index.mjs` in sideEffects prevented bundlers from
skipping concerto-core entirely when nothing from it is imported.

Instead, emit `dist/esm/dayjs-setup.js` as a separate file and reference
that in sideEffects — keeping the real side effect (dayjs.extend() calls)
declared while allowing the main ESM bundle to be tree-shaken at the
package boundary.

Verified: importing only concerto-util produces a 59 KB bundle;
adding concerto-core jumps to 1.46 MB, confirming the package is
correctly excluded when unused.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the
package is not "type": "module", Node parses a .js file as CommonJS, so
an ESM file with that extension is ambiguous. Emit it as .mjs and point
the sideEffects entry at the .mjs path so the dayjs.extend() side effect
stays correctly declared.

Also document in DEVELOPERS.md that the monorepo must be built in
dependency order (npm run build), because each package's exports.import
now resolves to dist/esm/index.mjs.

Addresses review feedback on PR #1263.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR makes the published @accordproject/* packages tree-shakeable at the package boundary by adding an additive ESM build (dist/esm/index.mjs), conditional exports, and accurate sideEffects metadata (with concerto-core isolating the dayjs.extend() side effect into a dedicated module).

Changes:

  • Add an esbuild-based ESM build step across workspace packages and wire it into package builds.
  • Introduce conditional exports + module fields and mark packages as side-effect-free (except concerto-core, which whitelists dayjs-setup).
  • Consolidate all dayjs.extend() calls into concerto-core/src/dayjs-setup.ts and add browser E2E coverage via Playwright + CI.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
scripts/build-esm.js New shared ESM build script (esbuild) used by workspace packages.
package.json Adds Playwright + esbuild dev deps, includes e2e workspace, and adds a root test:e2e script.
package-lock.json Lockfile updates for added dependencies/workspace.
DEVELOPERS.md Documents the need to build the monorepo in dependency order for ESM outputs.
.github/workflows/build.yml Adds a Chromium Playwright E2E job to CI.
e2e/.gitignore Ignores Playwright artifacts and node_modules for the new E2E workspace.
e2e/package.json New E2E workspace package and scripts to build then run Playwright tests.
e2e/playwright.config.ts Playwright runner configuration for Chromium project.
e2e/tests/browser-bundles.spec.ts New browser smoke tests to validate UMD bundles and dayjs plugin behavior.
packages/concerto-analysis/package.json Adds ESM build step + exports/module/sideEffects metadata.
packages/concerto-core/package.json Adds ESM build step + conditional exports and sideEffects whitelist for dayjs setup files.
packages/concerto-core/src/dayjs-setup.ts New consolidated dayjs plugin registration module.
packages/concerto-core/src/datetimeutil.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-core/src/factory.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-core/src/model/typed.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-core/src/serializer/jsonpopulator.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-core/src/serializer/resourcevalidator.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-core/src/serializer/valuegenerator.ts Switches to importing dayjs via the consolidated setup module.
packages/concerto-cto/package.json Adds ESM build step + exports/module/sideEffects metadata.
packages/concerto-linter/package.json Adds ESM build step + exports/module/sideEffects metadata.
packages/concerto-util/package.json Adds ESM build step + exports/module/sideEffects metadata.
packages/concerto-vocabulary/package.json Adds ESM build step + exports/module/sideEffects metadata.
packages/concertino/package.json Adds ESM build step + exports/module/sideEffects metadata.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread e2e/tests/browser-bundles.spec.ts Resolved
Comment thread scripts/build-esm.js Resolved
- e2e: import Page as a type-only import (it is used only as a type),
  avoiding a runtime named-import mismatch under some TS transpile modes.
- build-esm: gate the createRequire shim banner to the Node-only build.
  Browser-targeted .mjs outputs no longer carry a Node-only
  `import ... from "module"`, which could break downstream browser
  bundlers. Verified the browser bundles emit zero runtime require()
  calls (externals resolve as ESM imports), so the shim was unused there;
  the node-only package still receives it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
mttrbrts and others added 3 commits August 28, 2026 11:48
The browser-targeted ESM build externalised Node builtins, leaving bare
`import "fs"` (concerto-core, concerto-util) and `import "path"`
(concerto-util) in dist/esm/index.mjs. These only resolve in downstream
consumers that ship Node-polyfill/fallback infrastructure; a stricter
browser bundler would fail to resolve them.

Stub Node builtins to empty modules for browser builds via an esbuild
plugin (requires the async build API), matching the parity the webpack
UMD build already achieves via resolve.fallback (fs/path -> false). The
node-only linter build still externalises builtins and keeps its
createRequire banner.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
Decorated is the base class of all decorated model elements
(Declaration, Property, etc.) and was previously accessible only
via the types/lib/introspect/decorated deep import path. With the
exports field added in this PR, that path is no longer reachable.
Exporting it from the main entry point is the correct fix.

Signed-off-by: Matt Roberts <code@rbrts.uk>
issues.jsonl is a local beads issue-tracker data file that was
accidentally committed. Remove it and ignore it so it never
re-appears in diffs.

This fixes the license-check CI failure (the tool scanned the file
and found no Apache 2.0 header).

Signed-off-by: Matt Roberts <code@rbrts.uk>
@mttrbrts
mttrbrts force-pushed the fix/tree-shaking-sideeffects branch from 4f3e6ba to cab5fc7 Compare August 28, 2026 10:50
The exports field added for tree-shaking encapsulated each package to
./dist/* + ./package.json, which silently made the published ./types/*
declaration tree (shipped outside dist/) unreachable under node16/nodenext
and bundler resolution — a resolution regression for any consumer deep-
importing those supplemental .d.ts paths, which resolved fine before the
exports field existed.

Map ./types/* alongside ./dist/* on the four packages that publish a
types/ tree (util, cto, core, vocabulary) so the pre-existing deep-import
surface is preserved. Verified with a node16-resolution tsc probe that a
types/ deep-import now resolves (TS2307 before -> clean after).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
mttrbrts added a commit that referenced this pull request Aug 28, 2026
The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the
package is not "type": "module", Node parses a .js file as CommonJS, so
an ESM file with that extension is ambiguous. Emit it as .mjs and point
the sideEffects entry at the .mjs path so the dayjs.extend() side effect
stays correctly declared.

Also document in DEVELOPERS.md that the monorepo must be built in
dependency order (npm run build), because each package's exports.import
now resolves to dist/esm/index.mjs.

Addresses review feedback on PR #1263.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
@github-actions github-actions Bot added the maintainer-engaged A maintainer has commented or reviewed this item label Aug 28, 2026
mttrbrts added a commit that referenced this pull request Sep 4, 2026
….0.0) (#1306)

* feat(concerto): add tree-shakeable package entrypoints

Signed-off-by: Rishabh Jain <rishabhj2005@email.com>

* fix(concerto-core): remove ESM entrypoint from sideEffects to enable package-level tree shaking

Listing `./dist/esm/index.mjs` in sideEffects prevented bundlers from
skipping concerto-core entirely when nothing from it is imported.

Instead, emit `dist/esm/dayjs-setup.js` as a separate file and reference
that in sideEffects — keeping the real side effect (dayjs.extend() calls)
declared while allowing the main ESM bundle to be tree-shaken at the
package boundary.

Verified: importing only concerto-util produces a 59 KB bundle;
adding concerto-core jumps to 1.46 MB, confirming the package is
correctly excluded when unused.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(concerto-core): emit dayjs-setup as .mjs and document build order

The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the
package is not "type": "module", Node parses a .js file as CommonJS, so
an ESM file with that extension is ambiguous. Emit it as .mjs and point
the sideEffects entry at the .mjs path so the dayjs.extend() side effect
stays correctly declared.

Also document in DEVELOPERS.md that the monorepo must be built in
dependency order (npm run build), because each package's exports.import
now resolves to dist/esm/index.mjs.

Addresses review feedback on PR #1263.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(concerto): address Copilot review on ESM tree-shaking PR

- e2e: import Page as a type-only import (it is used only as a type),
  avoiding a runtime named-import mismatch under some TS transpile modes.
- build-esm: gate the createRequire shim banner to the Node-only build.
  Browser-targeted .mjs outputs no longer carry a Node-only
  `import ... from "module"`, which could break downstream browser
  bundlers. Verified the browser bundles emit zero runtime require()
  calls (externals resolve as ESM imports), so the shim was unused there;
  the node-only package still receives it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(concerto): stub Node builtins in browser ESM instead of bare imports

The browser-targeted ESM build externalised Node builtins, leaving bare
`import "fs"` (concerto-core, concerto-util) and `import "path"`
(concerto-util) in dist/esm/index.mjs. These only resolve in downstream
consumers that ship Node-polyfill/fallback infrastructure; a stricter
browser bundler would fail to resolve them.

Stub Node builtins to empty modules for browser builds via an esbuild
plugin (requires the async build API), matching the parity the webpack
UMD build already achieves via resolve.fallback (fs/path -> false). The
node-only linter build still externalises builtins and keeps its
createRequire banner.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(concerto-core): export Decorated from public API

Decorated is the base class of all decorated model elements
(Declaration, Property, etc.) and was previously accessible only
via the types/lib/introspect/decorated deep import path. With the
exports field added in this PR, that path is no longer reachable.
Exporting it from the main entry point is the correct fix.

Signed-off-by: Matt Roberts <code@rbrts.uk>

* chore: remove stray issues.jsonl and add to .gitignore

issues.jsonl is a local beads issue-tracker data file that was
accidentally committed. Remove it and ignore it so it never
re-appears in diffs.

This fixes the license-check CI failure (the tool scanned the file
and found no Apache 2.0 header).

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): ESM pilot — modelfile.ts + securityexception.ts (locks recipe R1-R10)

Pilot for #1304 (concerto-334). Migrates two exemplar files to native ESM:
- securityexception.ts: leaf, external named import (R3) + dual export (R1)
- modelfile.ts: requires->imports (R2), global-undefined block->import type (R7),
  export=->dual export (R1), field declarations for subclass type-debt (R10)

Locks the transformation recipe. Confirms: tsc-green is incremental per-file
(bucket-A field-decls self-checkable); migrated<->unmigrated seam errors
(bucket-B: TS2709/2351/2554) self-resolve at completeness.

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): native ESM migration — model batch (#1304)

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): native ESM migration — serializer batch (#1304)

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): native ESM migration — introspect-b batch (#1304)

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-util): native ESM migration — util batch (#1304)

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): native ESM migration — introspect-a batch (#1304)

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-core): native ESM migration — core-root batch (#1304)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(esm): resolve integration seam type errors after native-ESM migration

Phase C integration fixes for #1304. After migrating concerto-util and
concerto-core CJS-interop syntax to native ESM, workspace imports resolve
to their real types instead of `any` (previously masked by
`const X = require(...)`). This unmasked pre-existing latent type
inconsistencies at the migrated<->unmigrated seams. All fixes are
runtime-neutral (verified against the 455c779 baseline, which had 0 tsc
errors); no existing test files are modified.

- validationexception: `component?` (JSDoc already says optional; extends
  BaseException whose 2nd/3rd params are optional) — clears 20 TS2554
- jsonpopulator: `visit(thing: any)` — the Declaration|Field union does
  not share the duck-typed decl/field predicates called via `?.()`;
  `path?: TypedStack<string>` matches the value always assigned at runtime
- resourcevalidator: `constructor(options?)` — body already does
  `options || {}`; called with 0 args from factory.ts
- metamodel: drop dead trailing `true` 5th arg to ModelFile ctor
  (ctor has 4 params and never reads arguments[4]; baseline tolerated it
  only because `ModelFile` was `require(...)` = any)
- modelfile.getImports: annotate `result: string[]` (was inferred never[])
- jsongenerator: `let id: any = null` (matches sibling `result: any`)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(esm): use namespace import for uuid in factory (no ESM default export)

The migration converted `const uuid = require('uuid')` to
`import uuid from 'uuid'`, but uuid v9+'s ESM build exposes only named
exports (v4, etc.) with no default. tsc's esModuleInterop synthesized a
default (so the CJS build and .d.ts emit succeeded), but the esbuild ESM
bundle (build:esm) failed to resolve `default`. Usage is `uuid.v4()`, so
`import * as uuid from 'uuid'` is the correct, runtime-neutral form and
resolves cleanly under both tsc (CJS interop) and esbuild (native ESM).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* docs(esm): add #1304 plan + cross-session handoff

Captures the strategic fork (Options A hybrid / B v5 clean-break / C measure-first),
Phase-C implementation state, gating measurements, and resume instructions.
Branch is a resumable checkpoint pending a human release-strategy decision.

Refs: concerto-3oj, concerto-334

Signed-off-by: Matt Roberts <code@rbrts.uk>

* test(esm): migrate deep source requires to named exports (#1304)

Option B (clean break, v5) resolves the constraint conflict recorded in
plan-issue-1304-esm-migration.md §4: with leaf modules on native ESM,
`export default X` compiles to `exports.default = X` under `module: commonjs`,
so the existing `const X = require('../src/x'); new X()` pattern in the mocha
suites throws "X is not a constructor".

Under a major release those source-coupled requires are updated rather than
reverted. Each deep require now destructures the module's named export
(`const { X } = require('../src/x')`), falling back to `.default` where the
local binding does not match a named export.

- concerto-util: 85 passing / 66 failing -> 151 passing / 0 failing
- concerto-core: 93 passing / 279 failing -> 1276 passing / 0 failing

No source or public API changes; test wiring only. Also appends the required
licence header to the plan document so `license-check-and-add` passes.

Refs #1304

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto-cto,concerto-vocabulary): native ESM migration (#1304)

Completes the Option B clean break across the published surface. These were
the last two packages still on TypeScript's CJS-interop syntax; concerto-core
and concerto-util were migrated earlier on this branch, and concerto-analysis,
concertino and concerto-linter were already clean.

concerto-cto:
- `export = Class` -> `export { Class }; export default Class;`
- `export = { a, b }` -> individual named exports plus a default object of the
  same shape, so `Parser`, `Printer` and `External` keep their runtime shape
  while their members become individually tree-shakeable.
- `import X = require('./x')` -> `import X from './x'`, except the generated
  peggy parser, which has no default export and uses `import * as Parser`.
- `parseexception.ts` drops a `// @ts-ignore`d `require` for a real import.

concerto-vocabulary:
- `export = Class` -> named + default exports.
- The vocabulary <-> vocabularymanager cycle is removed at the source: the
  type-only direction becomes `import type`, which erases at compile time, so
  the compiled module graph has no cycle at all.

Public API surface is unchanged in both packages: the barrels export the same
names with the same runtime shapes. Test counts match baseline exactly
(cto 163, vocabulary 89).

Refs #1304

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(build): emit ESM as a module graph so packages actually tree-shake

Native ESM source syntax is a prerequisite for tree-shaking, not a sufficient
condition. The ESM build was flattening each package into a single
dist/esm/index.mjs, and once every module is inlined into one file there is
nothing left for `sideEffects` to act on: a consumer's bundler is reduced to
statement-level DCE across one large file, which the packages' cross-references
defeat immediately.

Measured before this change, importing `SecurityException` from concerto-core
- a two-line exception subclass - cost 544,356 B against a 559,367 B
whole-package ceiling. 97% of the package survived elimination.

Make every src/**/*.ts module an entry point and emit with outdir + splitting +
`.mjs` output extension, so the ESM build mirrors what tsc already produces for
CJS: one output module per source module, shared code hoisted into chunks.
dist/esm/index.mjs keeps its path, so main/module/exports are untouched.

Minified browser-bundle sizes, before -> after:

  concerto-core, SecurityException only   544,356 B ->   3,627 B  (-99.3%)
  concerto-core, ModelManager only        552,634 B -> 418,282 B  (-24.3%)
  concerto-core, whole package            559,367 B -> 547,863 B
  concerto-util, Writer only               17,215 B ->     739 B  (-95.7%)
  concerto-util, whole package             22,253 B ->  22,322 B

Whole-package imports are unchanged, as expected; the win is in what a consumer
does not import. ModelManager legitimately reaches most of the package, so its
24% is the honest floor for that symbol.

Verified: all seven packages emit index.mjs plus a per-module graph; a Node ESM
smoke test exercises ModelManager/Factory/Serializer round-tripping, CTO parse
and print, Writer, TypedStack and VocabularyManager against the emitted .mjs;
and a minified, tree-shaken consumer bundle that never imports dayjs-setup
explicitly still round-trips a DateTime with the utc plugin live, confirming the
one genuine module-level side effect in the tree survives shaking.

Refs #1304

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* docs(esm): add MIGRATION.md for v5 and record the Option B decision

MIGRATION.md is the consumer-facing guide for the 5.0.0 clean break: what
breaks (deep ./dist/* constructor imports, in both CJS and ESM form), what does
not (every root-package import), how to fix each, and the measured tree-shaking
numbers.

It also documents the type-import position: the packages deliberately do not
widen their `exports` map to re-expose the `types/` declaration tree. Consumers
should use `import type` from the package root, which is erased at compile time,
cannot anchor a module into a bundle, and resolves identically under every
module-resolution mode. Any type not reachable from a root barrel should be
added to that barrel rather than deep-imported.

The plan document records the Option B decision, the execution log, and the
tree-shaking measurement including the two hypotheses that were tested and
rejected before the real root cause was found.

Refs #1304

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(concerto-core): restore \u200C/\u200D escapes in ID_REGEX

The ESM migration replaced the escaped zero-width non-joiner and zero-width
joiner in ID_REGEX with the literal characters. They are invisible in a diff,
easy to corrupt through copy/paste or editor normalisation, and inconsistent
with the sibling regex in concerto-util's identifiers.ts, which kept the
escapes. Matching behaviour is unchanged.

Reported by Copilot on #1306.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(build): emit separate node and browser ESM builds

The ESM build stubbed Node builtins to empty modules for every non-linter
package, which is correct for a browser bundle and wrong for Node. Since the
`exports` map pointed the `import` condition at that build, Node ESM consumers
silently received stubs: `new FileWriter(dir)` threw "fs.mkdirSync is not a
function", and ModelWriter and ModelLoader failed the same way — at runtime,
not at build time.

Emit two ESM builds instead. dist/esm is node-targeted and keeps builtins
external, so `import` resolves to real fs/path. dist/esm-browser keeps the
stubbing and is routed through a new `browser` export condition, placed before
`import` so a browser bundler matches it first. Node-only packages get just the
node build.

Adding the `browser` condition means webpack now resolves sibling workspace
packages to their ESM build when producing the UMD bundles. Webpack treats .mjs
as fully specified, which breaks the extensionless request its `process`
ProvidePlugin injects, so the three UMD configs get a .mjs rule turning that
off; the sibling packages' own relative imports already carry extensions.

concerto-core's sideEffects now also lists the browser copy of dayjs-setup, so
the plugin registration survives shaking on both builds.

Verified: ModelWriter, FileWriter and ModelLoader all work through the node ESM
entry; the browser build still carries no bare builtin imports; tree-shaking is
unchanged on both (browser SecurityException 3,666 B against a 547,984 B
ceiling, Writer 739 B); full suite and the UMD browser e2e tests pass.

Reported by Copilot on #1306.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(build): bind process in the browser ESM build

3cb7b87 routes browser bundlers to dist/esm-browser through a new
`browser` condition. That graph leaves `process` free — the serializer
reads `process.env.TZ`, warning.ts reads `process.emitWarning`, bundled
deps read `process.env.NODE_ENV` — which used to be someone else's
problem only inside this repo, where the three UMD configs answer it
with ProvidePlugin. Now it is shipped, and it breaks downstream webpack
consumers: ProvidePlugin's extensionless `process/browser` request is
rejected as not fully specified once the importing module is .mjs.

accordproject/template-engine reproduces it — `npm run webpack` (part of
its `build:dist` and `prepublishOnly`) fails to build:

    ERROR in ./node_modules/@accordproject/concerto-util/dist/esm-browser/chunk-GG6UL5GV.mjs
    Module not found: Error: Can't resolve 'process/browser'
    BREAKING CHANGE: ... resolved as fully specified

Its config aliases concerto-core to the UMD bundle but not concerto-util,
so concerto-util resolves through the new condition. The `.mjs`
fullySpecified rule added to this repo's webpack configs fixes it here
and cannot reach a consumer's config.

Inject a process shim into the browser build instead, so the graph is
self-contained and no consumer needs a polyfill or a resolver rule. It
defers to a real `globalThis.process` when the page has one, so an
existing consumer polyfill still wins; the fallback covers only what
these packages read.

Verified: template-engine's webpack bundle builds again (0 errors) and
its 109 tests pass; concerto-playground builds and passes 328 unit +
104 e2e; this repo's suite and the 3 UMD browser e2e tests are
unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T
Signed-off-by: Claude <noreply@anthropic.com>

* test(esm): add a Node ESM smoke test and run it in CI

Every unit suite executes against src/ through ts-node, so nothing in
the repo exercises the emitted ESM. That is why serving the stubbed
browser graph to Node went unnoticed until Copilot read the build
script, and why a free `process` in the browser graph shows up only in
a downstream consumer's bundler.

The smoke test imports each package the way a consumer does and asserts
the fs-backed APIs actually touch disk, that ESM and CJS expose the same
names, and that the browser graph leaves no unbound `process`. Both
regressions fail it; the fixes pass it. Wired into build.yml after the
unit tests.

Adds `mjs` to the root license-check format list so the new script's
header is checked with the same comment style as `.js`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T
Signed-off-by: Claude <noreply@anthropic.com>

* docs(esm): document the two ESM graphs and the dual-package hazard

The exports-map reference still showed the single-graph shape from
before 3cb7b87. It now shows the `browser` condition and says which
graph a given runtime or bundler selects — nothing in consumer code
chooses between them.

The dual-package hazard gets its own section under breaking changes. In
4.x a package had no exports map and no module field, so `import` and
`require` landed on the same CommonJS file and a process held one copy.
From 5.0.0 they resolve to different files, so a process that reaches a
package both ways holds two sets of class identities and concerto's
`instanceof` guards start rejecting objects that are obviously the right
type:

    Error: "Serializer.toJSON" only accepts "Concept", "Event", "Asset",
    "Participant" or "Transaction".

This is inherent to shipping both module systems rather than something
to fix in the build, so the section says how to avoid loading a package
twice and how to recognise it when it happens.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T
Signed-off-by: Claude <noreply@anthropic.com>

* docs(esm): drop the #1304 planning document from the repo

plan-issue-1304-esm-migration.md was a cross-session handoff artifact — it
described itself as a resumable checkpoint and existed to carry WIP state
between working sessions while the migration was paused on the Option A/B/C
decision. That decision is made and the work is finished, so it is process
scaffolding rather than repository content.

Nothing references it. What is worth keeping has a better home: MIGRATION.md
carries the consumer-facing guidance, and the rationale, measurements and
rejected hypotheses are recorded in the pull request.

It also had to carry an appended licence header purely to satisfy
license-check-and-add, which is a sign it did not belong at the repo root.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* fix(build): keep runtime dependencies external in the node ESM build

The ESM build marked only workspace packages as external, so every runtime
dependency was compiled into the output. tsc does the opposite for the CJS
build, emitting require("dayjs"), which meant the two published artifacts
disagreed about what a dependency is.

Bundling gave each package its own private copy: debug was compiled into
concerto-util, concerto-core and concerto-cto independently, and an application
depending on all three shipped three copies and deduplicated none. It also hid
those dependencies from npm audit and SBOM tooling, and made a patch to any of
them require republishing concerto rather than a lockfile bump.

Published dist/esm, .mjs bytes:

  concerto-util          75,726 ->  40,887   -46%
  concerto-core         958,029 -> 441,228   -54%
  concerto-vocabulary   349,284 ->  87,639   -75%
  concerto-cto          505,039 -> 491,738    -3%
  total                       1,888,078 -> 1,061,492   -44%

Consumer bundle sizes barely move (-0.3% to -0.8%): the remaining duplication
is @accordproject/concerto-metamodel, which has to stay bundled — see below —
and it dominates what the packages share. The win here is the published
artifact and dependency hygiene, not the consumer's bundle.

The browser build still bundles its dependencies and its output is unchanged
byte-for-byte. It is consumed as a self-contained graph, and its Node-builtin
stubbing only holds if the dependencies reaching for builtins are resolved
here rather than by the consumer.

Four dependencies stay bundled because they are CommonJS with no ESM build and
Node's cjs-module-lexer cannot see their named exports; externalising them
emits `import { MetaModelUtil } from '...'` and Node throws "Named export not
found" at load time. The exception list carries the command to re-test them.

Two source imports needed file extensions. dayjs and @stoplight/spectral-cli
publish no exports map, so Node ESM rejects an extensionless subpath: bundling
had been resolving `dayjs/plugin/utc` by extension inference, and once the
specifier survives into the output it has to be `dayjs/plugin/utc.js`. Both
forms work unchanged under CommonJS.

Verified: npm run test:esm 10/10 (it caught both failures above before they
could ship), full monorepo suite unchanged, UMD browser e2e 3/3, lint and
licchk clean, dist/esm-browser byte-identical.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* build: run the ESM smoke test as part of the build

The smoke test exercises the emitted ESM rather than src/, so it only ran as a
separate CI step. That left the feedback loop backwards: both regressions it
has caught came from editing scripts/build-esm.js, and the contributor editing
that file got a clean `npm run build` locally and learned about the breakage
from CI minutes later.

Hooking it to postbuild puts the check where the failure is: a build that emits
a package which cannot be imported has failed. It also gates publishing for
free, since publish.yml runs `npm run build` before `npm publish`.

It has to hang off the root build, not an individual package's. The script
imports all four packages by name, so it needs the full ordered build to have
finished; a postbuild on concerto-util would fire during build:level0, before
core and cto exist.

The dedicated CI step is now redundant and removed — it would otherwise run
twice on each of the six matrix legs, plus again in the e2e job, which builds
through pretest:e2e.

Verified the guard actually bites: reintroducing the extensionless
`dayjs/plugin/utc` import makes `npm run build` exit 1 rather than emitting a
broken artifact. Costs 1.7s against a 51s ordered build.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* feat(concerto)!: drop the UMD browser bundles

The webpack UMD builds are removed from concerto-core, concerto-util and
concerto-cto, along with the legacy top-level `browser` field that pointed at
them.

The `exports` map introduced for tree-shaking had already demoted them: it is
consulted before the legacy `browser` field, so webpack 5, Vite, Rollup and
esbuild were resolving the root import to dist/esm-browser rather than the UMD
bundle. That was measurable downstream — concerto-playground's production
bundle dropped 14% on this branch precisely because Vite stopped using the UMD
build. What remained was a ~1MB artifact serving `<script src>` users and
tooling too old to read `exports`.

Removing it takes roughly a third off the ordered build (concerto-core's
webpack step alone was 13.8s of ~51s) and drops webpack, webpack-cli,
babel-loader, @babel/preset-env, node-polyfill-webpack-plugin and process from
devDependencies — 241 packages out of the lockfile. The four .babelrc files go
with them: they existed only to feed babel-loader inside the deleted webpack
configs, and left in place would have pointed at an uninstalled preset.
concerto-vocabulary's was already dead.

The `browser` *condition* inside each `exports` map is untouched. That is the
supported browser entry point and is what bundlers already use.

The browser e2e tests are rewritten against the ESM graph rather than deleted,
which closes a real gap: dist/esm-browser is the artifact browser consumers now
receive and nothing tested it in a browser. Doing so needed two things the UMD
tests never did. A module graph cannot be injected with addScriptTag — it
imports sibling chunks by relative path — so the suite serves each package's
dist/esm-browser over HTTP and imports it. And concerto-core's graph imports
@accordproject/concerto-cto and -util as bare specifiers, which a browser
cannot resolve, so the page carries an import map. Navigating to about:blank
first, as the UMD suite did, fails: Chromium's Private Network Access check
blocks a null-origin page from fetching loopback, so the server also serves a
same-origin document to land on.

Also adds e2e/.eslintrc.yml. That directory had no working TypeScript ESLint
setup — `npx eslint .` failed to parse even the pre-existing spec — and it now
holds two TypeScript files worth linting. Scoped with `root: true`.

BREAKING CHANGE: the UMD bundles dist/concerto-core.js, dist/concerto-util.js
and dist/concerto-cto.js are no longer published, and the `window['concerto-core']`
style globals they exposed are gone. Bundler users are unaffected. `<script src>`
users need a bundler or a module-type script; MIGRATION.md documents both.

Verified: build clean with the ESM smoke test passing, full suite unchanged
(1276/163/151/89/99/18/19), browser e2e 3/3 against the ESM graph, lint clean
across all four changed areas, licchk clean, and no dist/concerto-*.js emitted.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* docs(esm): correct the browser-resolution notes for the UMD removal

Two inaccuracies, both introduced by describing the browser story before the
UMD bundles were actually removed.

The bundler-user note explained that nothing changes for them "because exports
takes precedence over the legacy browser field". That framing describes a
conflict that no longer exists: the legacy browser field is gone. Reworded to
say what is now true — those tools read exports, so they had already stopped
using the UMD bundle, and removing it takes away something they were not
resolving to.

More substantially, the document listed only bundler users and script-tag users
as affected. It missed the group that actually gets the worst of this: tooling
that does not read exports at all. webpack 4, browserify and Parcel 1 found the
UMD bundle through the top-level browser field, and with both that field and the
bundle removed they now fall back to main — the CommonJS build, which imports fs
and will not run in a browser. That failure is real and surfaces as a confusing
missing-module error, so it is now called out explicitly, along with the fact
that there is no supported path for those tools in 5.0.0.

Co-Authored-By: Claude <noreply@anthropic.com>

Signed-off-by: Matt Roberts <code@rbrts.uk>

* build: externalise concerto-metamodel now that 3.17.0 is lexable

concerto-metamodel was the one runtime dependency held back from the Node
ESM build's externalisation list. Its CommonJS entry point assigned exports
with a string-literal object value, which halts cjs-module-lexer's scan, so
Node could not see the named exports and `import { MetaModelUtil } from
'@accordproject/concerto-metamodel'` threw at load time. Bundling it was the
workaround.

3.17.0 carries the upstream fix, so the workaround can go:

  parse(index.js).exports
    -> [ 'MetaModelUtil', 'MetaModelNamespace', 'DcsCto', 'DcsNamespace' ]

Raise the dependency floor to ^3.17.0 in the five packages that depend on
it. The floor is load-bearing rather than cosmetic: under ^3.16.0 npm could
resolve a version without the fix and the Node ESM build would break at
runtime.

Published artefacts shrink by the copies they no longer carry:

  concerto-core         441,228 -> 374,081 bytes  (-15%)
  concerto-vocabulary    87,639 ->  25,408 bytes  (-71%)

Bundled consumers see much less than that (a four-package bundle goes
587,881 -> 585,417, -0.4%): esbuild was already tree-shaking the inlined
copies down to the parts actually reached, and a single external CommonJS
copy cannot be tree-shaken, which offsets most of the deduplication. The
win here is install and download size, unbundled Node consumers, and having
one metamodel version in the tree instead of four.

The three @stoplight/spectral-* packages remain bundled; their named
exports are still invisible to the lexer.

Signed-off-by: Matt Roberts <code@rbrts.uk>

* docs(esm): re-measure the tree-shaking table under one consistent method

The published table mixed measurement methods: the 4.x column bundled a
package's `dist/index.js` directly while the 5.0.0 column resolved through
the `exports` map, and the numbers had drifted from the build as later
commits landed.

Re-measure both columns identically — import by package name, so resolution
happens the way it does in a consumer's project — and give the browser and
Node targets their own rows, since they resolve to different artefacts on
both sides. 4.2.0 ships no `exports` map, so a browser bundler takes its
`browser` field, which is the UMD bundle; that is what browser consumers
actually got, and it is why the browser column starts so much higher than
the Node one.

Signed-off-by: Matt Roberts <code@rbrts.uk>

* refactor(types)!: tighten introspect and model types, drop redeclared fields (#1308)

* refactor(types)!: tighten introspect and model types, drop redeclared fields

The ESM migration replaced `require()` with `import`, which restored real
base-class types across `concerto-core` and so switched property checking
back on. The migration papered over the resulting errors by declaring every
instance field as `: any`, including fields that the base class already
declared. This replaces those with real types.

Declared once, in the owning class
----------------------------------
- ClassDeclaration no longer redeclares `modelFile` (Declaration owns it).
- MapDeclaration no longer redeclares `modelFile`, `name` or `fqn`, and
  drops its `getModelFile`/`getName`/`getFullyQualifiedName` overrides,
  which were byte-identical to Declaration's. Its `process()` no longer
  recomputes `name`/`fqn` that `super.process()` has already set.
- Property dropped `modelFile`, which was declared but never assigned.
- ModelFile dropped `modelFile` and `ast`, likewise never assigned and
  already owned by Decorated.

Fields carry definite assignment assertions rather than initialisers
throughout: these classes are populated by a `process()` method that a base
constructor invokes, and with `useDefineForClassFields` off a subclass
initialiser is emitted after that constructor has run, clobbering the value.

Real types
----------
- `Decorated.ast` is now an exported `AstNode` interface, and `decorators`
  is `Decorator[]`. `getModelFile()` declares `ModelFile`, which removes the
  casts its callers needed.
- Declaration, ClassDeclaration, ScalarDeclaration, MapDeclaration,
  MapKeyType, MapValueType, Property, Field, RelationshipDeclaration,
  Decorator, ModelFile, Introspector and the four Validators carry concrete
  field and return types; nullable fields are `T | null` rather than `any`.
- `ModelFile.getDeclarations()` is generic, so `getAssetDeclarations()` and
  friends return their own declaration type.
- `NullUtil.isNull` and `ModelUtil.isValidIdentifier` are type predicates,
  which narrows at their call sites instead of forcing casts.
- BaseModelManager, Factory, Serializer, the serializer visitors, the model
  classes, DecoratorManager and DecoratorExtractor take concrete field
  types. New shared interfaces live in `types.ts`: `SerializerOptions`,
  `GenerateOptions`, `InstanceGeneratorParameters`, and the decorator
  command shapes mirroring the DCS model.
- `concerto-util` exports `WritableModelFile`/`WriteModelsOptions`;
  `concerto-cto` types `parse()` as `IModel`, gives `resolveExternal` a
  named options type, and drops the `as any` casts in FileDownloader.

Bugs the tightening surfaced
----------------------------
- Property and ModelFile passed an always-undefined `this.modelFile` to
  IllegalModelException; they now pass the real ModelFile.
- ScalarDeclaration passed `this.ast.name.location` as the *modelFile*
  argument to IllegalModelException, which was always undefined; it now
  passes `this.modelFile` and `this.ast.location`.
- ClassDeclaration.declarationKind() gained a `return ''` stub during the
  migration, silently answering with an empty string for any subclass that
  forgot to override it. It throws now, matching Decorated.getModelFile().

Downstream, concerto-analysis and concerto-vocabulary needed null guards
and narrowing casts where core methods now admit null.

Breaking: the emitted .d.ts files change shape. Runtime behaviour is
unchanged apart from the three exception arguments noted above.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAZpnt3uqfBeGWeKAcwHXS
Signed-off-by: Matt Roberts <code@rbrts.uk>

* refactor(types): address review, narrow validator ASTs to metamodel types

- CollectionSizeValidator, NumberValidator and StringValidator take their
  real metamodel nodes (ICollectionSizeValidator, the three domain
  validators, IStringRegexValidator/IStringLengthValidator) instead of the
  generic AstNode. Validator.validator is a union of those, and each
  subclass narrows it with `declare`, which emits nothing.
- Property.decorator is gone. It was only ever assigned null and never read
  in src or test.
- Decorator.handleError takes `string | Error` rather than `unknown`: the
  in-validate callers pass a message they just built, the catch passes the
  exception.
- Identifiable.$timestamp is `Dayjs`, not `any`, and the JSDoc on it and on
  the Identifiable/Resource/Relationship constructors says so. It was
  documented as a string but has always held a Dayjs, which is what
  JSONGenerator formats and JSONPopulator rebuilds.
- DecoratorExtractor keeps the explicit `> 0` comparison, via `?? 0`, rather
  than relying on a falsy length.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAZpnt3uqfBeGWeKAcwHXS
Signed-off-by: Matt Roberts <code@rbrts.uk>

---------

Signed-off-by: Matt Roberts <code@rbrts.uk>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Signed-off-by: Matt Roberts <7544022+mttrbrts@users.noreply.github.com>

* fix(esm): address type-safety review comments on PR #1306

jamieshorten's review flagged several `as unknown as` / `as X[]` casts
that the native-ESM migration introduced once real types replaced the
old CJS-interop `any`s.

- concerto-vocabulary/vocabulary.ts: getAllDeclarations() returns
  Declaration[], and the only member used here is getName(), so drop
  the unnecessary ClassDeclaration cast in favour of the real type.
- concerto-analysis/compare.ts: getAllDeclarations() is cast to
  ClassDeclaration[] so map/scalar declarations can flow through the
  same comparer pipeline. Verified runtime-safe (compareClassDeclaration
  guards with instanceof, and the public Comparer.compareClassDeclaration
  callback already has to tolerate this), so this is documented with a
  SAFETY comment rather than widened, since a type-level fix would mean
  changing the public Comparer callback's parameter type.
- concerto-core/basemodelmanager.ts: the two ModelWriter/FileDownloader
  casts are similarly runtime-safe (ModelFileLoader always supplies
  fileName/definitions; both ModelFileInstance and ModelFileSource only
  need to structurally satisfy `{ ast }`) but not provable by their
  current public interfaces, so both get a SAFETY comment explaining why.

No behaviour change. Full build (tsc + ESM emit + smoke test), lint and
the affected packages' unit tests (concerto-core 1278, concerto-analysis
99, concerto-vocabulary 89) all pass unchanged.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ECqBEJBSn19CRhCHLFmEw9
Signed-off-by: Claude <noreply@anthropic.com>

* refactor(types)!: fix the signatures the casts were hiding

Follow-up to the review on #1306. The three `as unknown as` / `as X[]` casts were
documented with SAFETY comments in a6a5688 on the grounds that removing them meant
changing public API. Since 5.0.0 is a breaking release, change the API instead: each
cast existed because a signature did not describe what the code actually does.

FileDownloader<TFile, TSeed = TFile>
------------------------------------
One type parameter served as both the input and the output of
downloadExternalDependencies(), but the files seeding the walk are not the type the
bound FileLoader produces: BaseModelManager seeds it with parsed ModelFile instances
and gets back raw ModelFileSource objects. The old signature could only be satisfied
by casting to `ModelFileInstance[] & ModelFileSource[]` — an intersection no element
can actually be. TSeed names the seed type and defaults to TFile, so existing
single-parameter uses are unaffected; getExternalImports takes `TFile | TSeed`,
which is exactly what it is handed at runtime.

Comparer.compareClassDeclaration takes a Declaration
----------------------------------------------------
Every declaration in a model file goes through this callback, map and scalar
declarations included, so `getAllDeclarations() as ClassDeclaration[]` was asserting
something false to satisfy a callback type that had always been narrower than
reality. Widening it to Declaration makes the compiler enforce what the runtime
already required: narrow before reaching for ClassDeclaration members. The built-in
comparers needed no changes — they only call Declaration-level methods and
getDeclarationType(), which already took a Declaration.

compareClassDeclaration()'s two negative instanceof guards collapse into one positive
`instanceof ClassDeclaration` check: ScalarDeclaration and MapDeclaration both extend
Declaration directly, so the positive form covers them and any future declaration
kind, rather than needing a new guard per kind.

writeModelsToFileSystem narrows instead of casting
--------------------------------------------------
WritableModelFile requires a fileName and definitions; ModelFile types both nullable
because a model file built from an AST alone has neither. That is real information,
not noise, so the call site now narrows and throws an error naming the namespace it
cannot write, rather than casting and letting fs raise a TypeError several frames
later. Managers loaded from CTO are unaffected.

MIGRATION.md documents all three under breaking changes.

Verified: full build (tsc, both ESM graphs, 10/10 ESM smoke checks), full suite
unchanged (concerto-core 1278, concerto-cto 163, concerto-util 151, vocabulary 89,
analysis 99, plus the jest suites), lint and licence checks clean. No runtime
behaviour change apart from the writeModelsToFileSystem error message.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ECqBEJBSn19CRhCHLFmEw9
Signed-off-by: Claude <noreply@anthropic.com>

---------

Signed-off-by: Rishabh Jain <rishabhj2005@email.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>
Signed-off-by: Claude <noreply@anthropic.com>
Signed-off-by: Matt Roberts <7544022+mttrbrts@users.noreply.github.com>
Co-authored-by: Rishabh Jain <rishabhj2005@email.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed.

@github-actions github-actions Bot added the Stale label Sep 13, 2026
@mttrbrts mttrbrts closed this Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

maintainer-engaged A maintainer has commented or reviewed this item Stale

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add tree-shaking support for web bundles

3 participants